home *** CD-ROM | disk | FTP | other *** search
/ Night Owl - The Best of BBS / Night Owl The Best of BBS (NOP-BBS) (Night Owl Publisher) (1994).iso / 022a / jm940310.lha / jamtool.doc < prev    next >
Text File  |  1994-02-14  |  17KB  |  486 lines
  1.  
  2.                           -==* JamTool 0.27 *==-
  3.  
  4.                             By James McOrmond
  5.                             February 14, 1994
  6.  
  7.  
  8. Note: Contact addresses, and the Changelog is at the end of this file.
  9.  
  10. -----------------------------------------------------------------------
  11.  
  12. 1) Installing JamTool
  13.  
  14. There   are   two   versions  of   Jamtool  included  in  this  archive
  15. (bin/Jamtool_T and bin/Jamtool_I).  The T version uses Traplist.library
  16. for  nodelist lookups,  and the I  version  uses  Igen.Library for  its
  17. nodelist lookups.  If you are planning on installing a nodelist on your
  18. system, you should select which of these two formats you wish to use,
  19. and pickup the utilities for that nodelist format.
  20.  
  21. The following files are available from my system:
  22.  
  23. IGEN1a34.lzh - IGEN Nodelist utilities.
  24. Traplist.lha - Traplist Nodelist Utilities. (traplist.library 5.2)
  25.  
  26. It is  recommended  to rename  the version  of JamTool  that  you  have
  27. selected  to use,  to JamTool  and make it  resident in  your  startup-
  28. sequence.  If you do not wish to spare the ram to make JamTool resident,
  29. make sure you put it somewhere in your search path.
  30.  
  31. An alias such as:
  32.  
  33. "alias lookup jamtool -ldcn "
  34.  
  35. is quite usefull.  (Old TrapDoor  users may  want to do a similar alias
  36. for the GetNode command).
  37.  
  38. This alias will add systems to your  cache list (if you remove the c it
  39. won't touch your cache).   You can use this with JTPhone to add systems
  40. to your phonebook from the nodelist.
  41.  
  42. -----------------------------------------------------------------------
  43.  
  44. 2) JTPhone
  45.  
  46. JTPhone is a new program i've added to the package.  It is used to edit
  47. the phone book file that Jamtool uses for its lookups.  The menu system
  48. is  very self-explanitory  so you should have no problems  figuring out
  49. what  you are  doing.   Basically  it allows  you to  edit the  list of
  50. systems in the s:JamTool.Phone list.  Because it creates your phonebook
  51. you do  not have to edit it manuall,  and you don't really need to know
  52. the format of the files either.   JTPhone also has an  option to import
  53. your cache list, so if you've done some outbound dialing to new systems
  54. and JamTool did a lookup for it,  and you now want  to add them to your
  55. phone book, you can easily do this.   It is  recommended that you strip
  56. down the Flags list.   Usually, you'll  just want  to list the relevent
  57. modem flags in there (V32b, Zyx, HST, etc.. whatever you support).
  58.  
  59. -----------------------------------------------------------------------
  60.  
  61. 3) Using JamTool with JamMail
  62.  
  63. JamMail is my own  WPL.library mailer.  If you are  running JamMail  on
  64. your  system  (or  are now  installing  it),  you do not  need  to read
  65. section 4 since JamMail looks after this stuff itself.
  66.  
  67. -----------------------------------------------------------------------
  68.  
  69. 4) Using JamTool in your own Applications (or from the CLI/Shell)
  70.  
  71. Usage: jamtool -command option {option} {option}.....
  72.  
  73.        jamtool -a line
  74.        jamtool -d wazoo.cap line
  75.        jamtool -e StartTime EndTime env:variable
  76.        jamtool -i env:variable
  77.        jamtool -l{c}{n}{d}{v} Address {nodelistpath}
  78.        jamtool -r system response
  79.        jamtool -s {u}
  80.        jamtool -t filename device unit baud flags
  81.        jamtool -v line
  82.  
  83.  
  84. ------
  85. AKA Lookup: (-a)
  86.  
  87.  
  88.   This function is used with the EMSI handshaking.  It takes the line
  89. number as the command line argument, and does a lookup (phone book only)
  90. of each address in the Env:$(line).Remote.Addresses variable.
  91.  
  92.   It creates 3 new Env:Variables: $(line).Remote.Addresses.Valid,
  93. $(line).Remote.Addresses.Invalid, and $(line).Remote.Addresses.Unknown.
  94.  
  95.   The Addresses in the Valid and the Unknown variables should be used
  96. for the BeginSession commands, and the Invalid addresses should be
  97. logged for the Sysop to deal with.
  98.  
  99.   The line number is added to the front of each variable so there are
  100. no problems on multi-line systems.
  101.  
  102. ------
  103. Lookup: (-l)
  104.  
  105.  
  106.   This is  the function  you will be  using to find the phone number or
  107. password  of a system  you want to  have a session with.   There is one
  108. required option, which is the address you are looking for, and a second
  109. option which is required if you turn on Env: Variables.
  110.  
  111.   The Lookup  function  is the  only function  where I check  the other
  112. letters of the command  option.   If a c is found,  the t:jamtool.cache
  113. file  will be  used when appropriate.   If an n is found,  the Nodelist
  114. will be searched when appropriate.   If a d is found,  the display will
  115. have a little bit more information than when its not.   If a v is found
  116. then Env: variables will be written if the system is found.
  117.  
  118.  The Flow of the Lookup function is as follows
  119.  
  120.  Look for the system in the Phonebook.
  121.  If not found and the Cache is enabled, look there.
  122.  If not found and the Nodelist is enabled look there
  123.  If I found it in the nodelist, and the cache is on, add to the cache
  124.  If I found the system, and the variables are on, write the variables.
  125.  
  126.  
  127.  3. Work:jamtool> jamtool -lcnd 1:224/100
  128.  Address: FIDONET#1:224/100.0 (-)
  129.  System : Jammy's Amiga Corner
  130.  Phone  : 1-705-566-1991  Type: FIDO
  131.  Sysop  : James_Mcormond (Sudbury_ON)
  132.  Flags  : V32B,V42B,ZYX,CM,XA,9600
  133.  Hub    : 60, Region: 12
  134.  Cost   : 0
  135.  
  136. This is the output  displayed when Full  display is turned on,  and the
  137. system was found in the nodelist (not the Cache or phonebook).
  138.  
  139.  3. Work:jamtool> jamtool -lcdn 163/109
  140.  Address: FIDONET#1:163/109.0 (-)
  141.  Phone  : 1-613-230-2282  Type: FIDO
  142.  Sysop  : Russell_McOrmond (Ottawa_ON)
  143.  Flags  : ZYX
  144.  
  145. This  is the output  displayed  when Full display is  turned on and the
  146. system  is found  in the  Cache  or Phonebook.   The Phone  number line
  147. would not be displayed if the extended display option was not on.
  148.  
  149. The following ENV: variables are set when you turn Env: Variables on.
  150.  
  151. $(stem).City
  152. $(stem).Cost
  153. $(stem).Flags
  154. $(stem).MaxBaud
  155. $(stem).Number
  156. $(stem).Password
  157. $(stem).SiteName
  158. $(stem).Sysop
  159.  
  160. ------
  161.  Type file: (-t)
  162.  
  163. This function is  relatively straight  forward.  It takes the  required
  164. command  line  options,  and outputs  a regular  text file  to the user
  165. through the given serial device.
  166.  
  167. I run it in Jammail.wpl like this.
  168.  
  169.   system "jamtool -t text:$(username) $(device) $(unit) $(baud) $(serflags)"
  170.  
  171. which prints a text file name (in the variable username) to the user on
  172. this line.
  173.  
  174.  
  175. ------
  176.  Dialing Response Code: (-r)
  177.  
  178. This function takes two options, the first one being the systems address
  179. and the second being the response type as returned from the modem after
  180. a dial ("CONNECT", "BUSY", "MAID", etc).
  181.  
  182. The first parameter, is not to be a regular Fido style address.  If the
  183. system called, was not a Fidonet system, the address is passed unmodified
  184. to JamTool, if the address is a Fidonet system, then the address should
  185. be sent in the following form:
  186.  
  187. Zone.Net.Node.Point.Domain.
  188.  
  189. The following WPL code is used in JamMail for this function.
  190.  
  191.  
  192.    cmpi $(remote.type) FIDO
  193.    FalseJump NotFidoDoDial
  194.    RexxMsg SY REXX "Address 'COMMAND' 'JamTool -r $(Remote.Zone).$(Remote.Net).$(Remote.Node).$(Remote.Point).$(Remote.Domain) $(event)'"
  195.    Jump AfterTypeCheckDoDial
  196.   NotFidoDoDial:
  197.    RexxMsg SY REXX "Address 'COMMAND' 'JamTool -r $(Remote.Address) $(event)'"
  198.   AfterTypeCheckDoDial:
  199.  
  200. This code is immediately after the GetResponse command after the Dial
  201. command.
  202.  
  203. ------
  204.  Scheduler: (-s) option
  205.  
  206.  This function scans XferQ.library for systems with outbound mail of at
  207. least priority 50  (crash) (or the number  stored in the ENV:  variable
  208. "minpri"),  and scans the UUSPOOL:  directory for  C.#? files  to go to
  209. sites listed in your UULIB:l.sys file and creates a list of environment
  210. variables with the sites to call.
  211.  
  212.  $(JamTool/todial)   the number of sites to dial
  213.  $(JamTool/todial-1) site number 1 to dial
  214.  $(JamTool/todial-2) site number 2 to dial
  215.  
  216.  etc..
  217.  
  218. The Scheduler  built into  versions of  JamMail higher than .96 all use
  219. this function.
  220.  
  221. As of JamTool 0.23 this scheduler now counts the number of busy signals
  222. and failed connections (via the -r option above), and will dial less
  223. often if you still have not connected to this system.  The following
  224. function is used to determine the number of "loops" through the
  225. scheduler will be waited until the next dial for this system.
  226.  
  227. towait = (((bad*3)+busy) / 10)
  228.  
  229. Each bad connect is equivalent to 3 busy signals.  After each 15 busy
  230. signals, the system will up the number of loops that it must wait
  231. before dialing the system again.
  232.  
  233.  
  234. ------
  235.  Wazoo Bit Decode: (-d)
  236.  
  237. This option  provides  you with  a "pretty"  bit display for your logs.
  238. Instead  of displaying just the Wazoo Bits number, you can also display
  239. exactly what each bit means.
  240.  
  241. In JamMail.wpl, this is how I use the decode option.
  242.  
  243.   System "JamTool -d $(remote.wzcap) $(line)"
  244.  
  245. If  $(remote.wzcap)  contained the  number 49165, the env:$(line).WaZoo
  246. variable would include the following string.
  247.  
  248.  >  DietIFNA ZedZip ZedZap +Freq +Domain
  249.  
  250. which you can print in the Wazoo: display routine in your .wpl language
  251. file.
  252.  
  253.  
  254. ------
  255.  IsValid: (-i)
  256.  
  257. This option takes the name of an environment variable as its option.
  258. It will scan the line for special control characters and tell you if
  259. the string is invalid.  It will return 5 if it finds a character that
  260. it doesn't like.
  261.  
  262. The following characters are scanned for:
  263.  
  264. '  `  ~  $  "
  265.  
  266.  
  267. ------
  268.  Total Session time Calculator: (-e)
  269.  
  270. This option takes 3 options.   The Start time (hh:mm:ss), the  End time
  271. (hh:mm:ss)  and the variable name that it will stick  the difference in
  272. (hh:mm:ss  format).   This is used  to provide  the Total  Session Time
  273. displayed on the End of Session log line.
  274.  
  275.  
  276. > [1] 19:29:14 End of Session with FidoNet#1:224/30.0 Duration: 00:01:25
  277.  
  278.  
  279. ------
  280.  Pretty Version Strings: (-v)
  281.  
  282. This option  will possibly be removed  from the  program as  its not as
  283. relevent as it first was when I first wrote it.
  284.  
  285. I run it in the following way in  my Startup: routine in my JamMail.Wpl
  286. file.
  287.  
  288.  startup:
  289.    set currentlog all
  290.    set stack 32000
  291.    PutLog ""
  292.    system "jamtool -v M"
  293.    PutLog "[M] $<time> Startup on ${M.Date} with ${WPLName}"
  294.    PutLog "[M] $<time> ${M.Version}"
  295.  
  296. which produces a log such as:
  297.  
  298.  >
  299.  > [M] 14:05:46 Startup on Sunday 21-Feb-93 with WPL 0.86.01
  300.  > [M] 14:05:46 Kickstart version 37.175. Workbench version 37.71
  301.  
  302. The $(stem).Version string  is really not necessary,  since Version can
  303. be run as an  Echo option in KS2.0 (to get rid of  the line feed on the
  304. end),  but I had  done this option  before we found this out.  The only
  305. difference between  $(stem).Date and the  internal $<date>  function is
  306. the day word, which is what i was wanting.
  307.  
  308. -----------------------------------------------------------------------
  309.  
  310. 5) The S:Jamtool.phone and t:Jamtool.Cache files
  311.  
  312. Both of  these files  are  exactly the  same format.   Actually, when I
  313. first wrote the version of  JamTool that  supported these files, I used
  314. jamtool to create a  t:jamtool.cache  file (through nodelist  lookups),
  315. and then copied this file as my s:jamtool.phone file.
  316.  
  317. The format of the file is as follows.  One system per line.
  318.  
  319. Address Phone Type PassWd Flags Location Sysop
  320.  
  321. The address must be either a text address, or a full 5d FTN address.
  322.  
  323.    eg. Fidonet#1:163/139.0
  324.    
  325. The phone number field is self-explainatory.   This is the number  that
  326. is dialed to reach this system.   (JamMail  users that  are using a  LD
  327. phone  routing service  should look  into the  LDPhone Options  if they
  328. wish to prepend a number to this  phone number).   Local phone  numbers
  329. should not have prefixes and such on them.
  330.  
  331.    eg. 1-613-521-0455
  332.     or:
  333.        521-0455  (if its a local call)
  334.  
  335. There are a few types supported with JamMail.  Users of other  software
  336. may want to put a - in this field if your mailer doesn't use this field
  337. itself.
  338.  
  339.      FIDO - When connected, start a Fidonet session with this site.
  340.      UUCP - When connected, launch UUCICO for a UUCP session.
  341.      NRC  - Used for calling Atomic clock systems.
  342.      TERM - When connected, launch a terminal program.
  343.      FAX  - When connected, lauch fax software (not used yet).
  344.  
  345. Currently JTPhone only supports the first 4.
  346.  
  347. The PassWd field should contain  the password  that you wish to use for
  348. sessions with this system.
  349.  
  350. The Flags  field should contain a bit of information about the modem on
  351. the  other end.  JamMail  uses this field  to check  against  a list of
  352. parameters that the user can configure,  and it will use a  custom dial
  353. string for specific modem types.  If you are importing systems from the
  354. nodelist,  you will  want to clean a  lot of the nodelist flags  out of
  355. this field as you won't be using them.  See section on JTPhone for more
  356. information.
  357.  
  358. The last two fields,  Location and Sysop  are used for display purposes
  359. only.
  360.  
  361. Eg.
  362.  
  363. Fidonet#1:163/109.0 230-2282 FIDO - v32b Ottawa Russell_McOrmond
  364.  
  365. Note:  If you support UUCP sessions  on your system, you  will  need an
  366. entry  for  inbound calls,  and  one for  outbound calls.   The inbound
  367. entry should have a "UU" on the front of the name.
  368.  
  369. eg.
  370.  
  371. Jammys 521-0455 UUCP - v32b,zyx Ottawa James_McOrmond
  372. UUJammys - UUCP passwd v32b,zyx Ottawa James_McOrmond
  373.  
  374. The password field is not currently used on Outbound calls,  so you are
  375. expected to keep working entries in your uulib:l.sys file.
  376.  
  377. The following fields can be replaced by a "-" character if they are not
  378. appropriate, or necessary for that entry.  (JamMail users)
  379.  
  380. Sysop     - not worried about display
  381. Location  - (again, not necessary)
  382. Password  - outbound UUCP sessions
  383. Phone     - inbound UUCP sessions
  384.  
  385.  
  386. -----------------------------------------------------------------------
  387.  
  388. If you need to contact me, these are my Addresses.
  389.  
  390. FidoNet#1:163/139.0
  391. ZyXELNET#18:163/139.0
  392. InterNet: ab207@Freenet.Carleton.Ca
  393. UUCP: Jam@Jammys.OCUnix.On.Ca (Email costs)
  394.  
  395. Also you can get ahold of me in any number of the Amiga Fidonet related
  396. conferences (Especially the WELMAT or AMY_Point) conference, as well as
  397. most of the UseNet Comp.Sys.Amiga newsgroups, especially 
  398. Comp.Sys.Amiga.Datacomm.
  399.  
  400. Current versions of JamTool are always available by dialing my system
  401. 1:163/139 (613)521-0455, typing "freq", and then typing "JamTool".
  402.  
  403. -----------------------------------------------------------------------
  404.  
  405.                ----------=== Jamtool Changelog ===----------
  406.  
  407.  
  408. V0.10 - Intial release.  Sunday February 21, 1993
  409.  
  410. V0.11 - shows all command line arguments in window for debugging.
  411.  
  412. V0.12 - If there is a second digit after the f in the -f option
  413.         (ie -FIDO as in the above example), the tiny display will be
  414.         put there, but if there is only a -f, then there won't be a
  415.         display.  This is to remove the display from being show when
  416.         the Wazoo: routine is looking up the sites password (and City
  417.         in Jammail.wpl).
  418.  
  419. V0.13 - Added regular fido lookup function which displays the same
  420.         information the regular -fido option does, but it doesn't
  421.         set any ENV: variables.      (Thu Feb 25)
  422.  
  423. V0.14 - working on type function.  (Mon Mar 1)
  424.  
  425. V0.14+ - Type function works.  Requires filename, device, unit, baud
  426.         and serial flags ($(serflags) variable).
  427.  
  428. V0.15 - -L option fixed.
  429.  
  430. V0.16 - -S(cheduler) Option added.  Scans for UUCP and Fido outgoing mail
  431.  
  432. v0.17 - fixes to scheduler - does not dial UUCP sites without "any" in the
  433.         second field of the l.sys file.
  434.  
  435. v0.17b - bug fixes
  436.  
  437. v0.17c - something
  438.  
  439. v0.18 - Visual changes as requested by Robert.  Domain displayed in Lookup
  440.         is the same domain given (if one is given).  (bits) part removed
  441.         from WaZoo decode line and +domain moved to last field displayed.
  442.  
  443. v0.18b - -E option.  It subtracts the time difference between the two time
  444.         values given.  This allows me to give the "total session time"
  445.         used in the End of Session log line.
  446.  
  447. v0.20 - completely re-did all of the "lookup options" to use the phone
  448.         book and cache files.  All addresses are parsed by Xferq.Library
  449.         and are converted to uppercase for a case-insensative match on
  450.         the phonebook and cache files.
  451.  
  452. v0.20b - added env:minpri variable for scheduler to set the lowest
  453.         priority that will be scanned for.
  454.  
  455. v0.21 - New Lookup function.  There is now a single Lookup command with
  456.         4 possible flags.
  457.  
  458. v0.21a - Completely cleaned JamTool up.
  459.  
  460. v0.22 - JamTool Phone book editor added to archive.
  461.  
  462. v0.22a - JTPhonebook updated (v1.02).
  463.  
  464. v0.22b - JTPhonebook updated (v1.03).  Optimizing all 3 binaries now.
  465.         JamTool now identifies Hydra in Wazoo Bit field.
  466.         Entry of "Session type" fixed in JTPhone Add function.
  467.  
  468. v0.23 - Scheduler now figures out how often it should dial a system
  469.         based on the number of Busy signals and bad connections it has
  470.         received attempting to dial the system since its last outbound
  471.         connection.  New Option "-r" added used for setting up this
  472.         "Data base" of responses for each system.
  473.         
  474. 0.23b - Scheduler dialing adjuster now changes after 10 "busy" responses
  475.         instead of 15.
  476.  
  477. 0.24 - 0.26 - lots of small changes - AKA lookup function added
  478.        (missing documentation :-)
  479.  
  480. 0.27 - AKA password lookups are now sped up a very large amount!
  481.        previously the s:jamtool.phone file was searched for each AKA
  482.        and the passwords checked one at a time.  I am now reading
  483.        the s:jamtool.phone into a linked list in ram, and search
  484.        for each AKA that way.
  485.  
  486.